sec (9/9): document that scanners must not print secrets into raw evidence#33
Merged
Merged
Conversation
jesse-merhi
force-pushed
the
sec/08-explicit-sandbox-mounts
branch
from
July 26, 2026 02:38
04c6ca8 to
e20d07d
Compare
jesse-merhi
force-pushed
the
sec/09-doc-raw-evidence-secrets
branch
from
July 26, 2026 02:38
a5e0f41 to
e0dc381
Compare
clawsweeper
Bot
added
rating: 🦪 silver shellfish
|
Codex review: needs maintainer review before merge. Reviewed July 27, 2026, 9:00 AM ET / 13:00 UTC. ClawSweeper reviewWhat this changesThis PR documents that user-defined scanners must keep credentials out of raw JSON evidence and corrects the documented custom scanner-ID constraints. Merge readiness✅ Ready for maintainer review Keep open. This is a narrow, correct documentation update, and the previous blocker is resolved: the declared- **Likely related people**
Priority: P2 Review scores
Verification
How this fits togetherProfile-defined user scanners run external commands through ClawScan's scanner runner. Their valid JSON stdout is retained as raw evidence, while declared secret environment values are redacted only from failure text before artifacts are written. flowchart LR
Profile[Profile scanner configuration] --> Runner[User-defined scanner runner]
Secrets[Declared secret environment names] --> Runner
Runner --> Sandbox[Sandboxed scanner command]
Sandbox --> Split[Stdout and stderr handling]
Split --> Evidence[Raw JSON evidence]
Split --> Errors[Redacted failure text]
Evidence --> Artifacts[Run artifacts]
Errors --> Artifacts
Before mergeNone. Agent review detailsSecurityNone. Review metrics
Technical reviewBest possible solution: Retain raw scanner JSON as evidence, keep declared Do we have a high-confidence way to reproduce the issue? Not applicable: this PR changes documentation only. Its central claims align with the merged redaction work and the existing raw-evidence contract described in the related implementation history. Is this the best way to solve the issue? Yes. Warning scanner authors not to emit credentials in raw JSON is the narrow maintainable solution because preserving scanner evidence verbatim is an intentional artifact contract; rewriting arbitrary third-party JSON could alter evidence. AGENTS.md: found and applied where relevant. Codex review notes: model internal, reasoning high; reviewed against a9b45ab69396. LabelsLabel justifications:
EvidenceWhat I checked:
Likely related people:
Rating scale
Overall follows the weaker of proof and patch quality. Workflow
HistoryReview history (1 earlier review cycle)
|
…er evidence ClawScan preserves a user-defined scanner's stdout verbatim as raw evidence, so a secret the scanner prints into its own JSON output is persisted as-is. Unlike declared env values in error text, ClawScan cannot redact inside raw evidence without corrupting it. Document that a scanner must not echo credentials into its report (finding 9, resolved as a documented author contract rather than code). Also correct the scanner id rule to note the lowercase and 64-character limits added in the hardening series.
jesse-merhi
force-pushed
the
sec/09-doc-raw-evidence-secrets
branch
from
July 27, 2026 12:57
e0dc381 to
75c8fbb
Compare
clawsweeper
Bot
added
rating: 🐚 platinum hermit
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this documents
A user-defined scanner must not print credentials into the JSON report it emits. ClawScan preserves valid scanner stdout as raw evidence, so a secret placed inside that JSON is intentionally not rewritten.
secretEnvprotects scanner failure text:It does not transform scanner evidence:
{"scanner_output":"credential-value"}That JSON remains raw. Avoiding secrets in it is the scanner author’s responsibility. The docs also correct the scanner ID contract to lowercase IDs of at most 64 characters.
Verification
go test -count=1 ./internal/runner -run '^TestUserDefinedScannerPreservesSecretEnvInRawEvidence$' -v— passed\n-make docs-site— passed\n\nDocumentation only; no runtime code changes.